---
title: Remote sources
description: Use remote sources as though they were installed modules
sidebar_label: Remote sources
---

:::info Experimental

This feature is flagged by webpack as **experimental** and, as such, it is opt-in.

If you use this feature and bump into a problem please ensure that
**bud.js** is doing something wrong before opening an issue in the roots/bud repository. Consider accompanying your issue with
a PR that implements the change you would like to see.

:::

You can build remote packages at compile time, serve them locally, and generate a lockfile to guarantee deployed dependencies match your development environment.

Ships with support for the following sources, but you can add more:

- `skypack`
- `gist`
- `github`
- `unpkg`

## Basic usage

First, enable the feature:

```ts title=bud.config.js
export default async bud => {
  bud.cdn.enable()
}
```

Once enabled, try importing a module using one of the built in sources:

```ts title=app.js
import confetti from 'skypack:canvas-confetti'
confetti()
```

If you are referencing a github URL, note that you will need to include a branch:

```ts title=app.js
import readme from 'github:roots/bud/main/README.md'
```

If you are specifying any asset with a remote URL (e.g. an image) it will automatically convert it to a local module. For example, referencing an image in CSS will download that image to the store and map the URL to the local module:

```css title=app.css
body {
  background-image: url('https://example.com/image.png');
}
```

## Import mapping

You can use `bud.imports` in `package.json` to map sources to application modules.

```json title="package.json"
{
  "bud": {
    "imports": {
      "skypack": ["canvas-confetti"]
    }
  }
}
```

Now, in your application code you can import `canvas-confetti` as if it were a traditionally installed module:

```js title=app.js
import confetti from 'canvas-confetti'
confetti()
```

This approach makes your application more standard and less dependant on build tool magic.

## Setting custom sources

Registered sources are stored as a `Map` in `bud.cdn.sources`.

To add your own source:

```ts title=bud.config.js
bud.cdn.sources.set('localhost', 'https://localhost:8080/')
```

Once added it can be used in the same way as the built-in sources:

```ts title=app.js
import test from 'localhost:8080/test.js'
```

To remove a source (built-in or custom):

```ts title=bud.config.js
bud.cdn.sources.delete('gist')
```
